git worktree

Git을 쓰다 보면 이런 상황이 자주 생긴다.

긴급 핫픽스 브랜치를 잠깐 처리해야 한다.
현재 작업 중인 브랜치의 변경사항은 보존하고 싶다.
동시에 다른 기능 브랜치를 확인해야 한다.

보통은 git stash를 쓰거나 새로 클론을 받지만, 더 깔끔한 해법이 있다. 바로 git worktree다.

Worktree란?

git worktree는 하나의 Git 저장소에서 여러 개의 작업 디렉터리를 만드는 기능이다.
즉, 한 저장소를 기준으로 여러 브랜치를 각기 다른 폴더에서 동시에 작업할 수 있다.

왜 유용한가?

컨텍스트 스위칭 최소화
stash와 checkout을 반복하지 않아도 된다.
빠른 브랜치 전환
각 브랜치를 별도 폴더로 유지하니 즉시 작업 가능하다.
**CI/테스트 병렬화
서로 다른 브랜치를 각 worktree에서 테스트할 수 있다.

기본 사용법

워크트리 생성

git worktree add <경로> <브랜치명>
git worktree add ../my-project-main main

브랜치 명을 생략하면 디렉토리 이름으로 브랜치가 자동 생성된다
-b 옵션을 사용해서 디렉토리 이름과 브랜치명을 다르게 할 수 있지만, 오히려 헷갈린다.

새 브랜치를 만들며 생성

git worktree add -b feature/new-feature ../feature-worktree

worktree 목록 확인

git worktree list

작업 디렉터리와 브랜치 상태가 한눈에 보인다.

이동

cd ../feature-worktree
git branch --show-current

각 워크트리는 독립된 폴더이므로, IDE에서도 별도 프로젝트로 열어 쓰면 된다.

worktree 제거

git worktree remove ../my-feature-branch

해당 디렉터리를 정리하고 worktree 등록에서도 제거한다.

실전 활용 패턴

main과 hotfix를 동시에 유지
코드 리뷰 중인 PR 브랜치를 별도 worktree로 열어두기
장기 기능 브랜치와 단기 실험 브랜치 병행

주의할 점

하나의 브랜치는 하나의 worktree에만 존재해야 한다.
.git은 공유되므로, 리모트/브랜치 정리는 공통으로 영향을 준다.

git stash, git clone과 비교

`git stash`와 비교

stash는 반복될수록 관리가 번거롭고 실수 위험이 있다.
worktree는 브랜치별 작업 디렉터리가 있으니 stash 자체가 필요 없다.

`git clone`과 비교

클론은 디스크 사용량이 크고, 설정/히스토리 공유가 불편하다.
worktree는 .git을 공유하므로 저장 공간과 관리 비용을 줄인다.

AI 에이전트와 git worktree

내가 처음 git worktree를 사용해본 건 여러 AI 에이전트들을 병렬로 사용해보면서다.
같은 프로젝트에서 여러 에이전트 작업들이 서로 영향을 주지 않기 위해서 사용했었다.
사용해보니 이 외에도 병렬 에이전트 작업 시에 다양한 장점들이 있었다. 잘못된 코드를 생성해도 워크트리를 삭제하기만 하면 된다던가, 브랜치보다 더 분리된 터미널 공간을 갖는다거나. 어찌보면 AI 에이전트에 필수적이라고 생각됐다.

찾아보니 이미 여러 AI 코딩 에이전트들 claude code, cursor 등에서 병렬 에이전트 작업에 git worktree를 사용하고 있었다. claude code agent teams 에서 병렬 agent를 사용할 때도 git worktree를 생성해 각 에이전트들 마다 작업 공간을 분리하는 것을 볼 수 있었다.

결론적으로 AI 에이전트를 사용한다면 git worktree에 대해서 알 필요가 있을 것 같다.